/**
 * 用户实体类
 * 
 * 功能说明：
 * - 存储用户的基本信息，包括用户名、密码、邮箱、手机号等
 * - 支持用户状态管理（启用/禁用、锁定/解锁）
 * - 支持多种认证方式（本地、微信、QQ、微博）
 * - 支持用户类型区分（普通用户、管理员、商家）
 * 
 * 数据库设计：
 * - 表名：users（使用复数形式，符合数据库命名规范）
 * - 主键：继承自BaseEntity的id字段
 * - 索引：username、email字段有唯一索引，确保数据唯一性
 * 
 * 字段约束：
 * - username：非空，唯一，用于登录
 * - password：非空，存储BCrypt加密后的密码
 * - email：非空，唯一，用于找回密码和通知
 * - enabled：默认true，表示账户是否启用
 * - locked：默认false，表示账户是否被锁定
 * 
 * 枚举类型：
 * - Gender：性别（男、女、未知）
 * - UserType：用户类型（普通用户、管理员、商家）
 * - AuthProvider：认证方式（本地、微信、QQ、微博）
 * 
 * 审计字段：
 * - 继承BaseEntity的createdAt、updatedAt字段
 * - lastLoginTime：记录最后登录时间，用于安全分析
 * 
 * @author eCommerce Team
 * @version 1.0
 */
package com.ecommerce.auth.entity;

import com.ecommerce.common.entity.BaseEntity;
import jakarta.persistence.*;
import lombok.Data;
import lombok.EqualsAndHashCode;

import java.time.LocalDateTime;

/**
 * 用户实体类
 * 存储用户基本信息和状态，支持多种认证方式
 */
@Data
@EqualsAndHashCode(callSuper = true)
@Entity
@Table(name = "users")
public class User extends BaseEntity {

    /**
     * 用户名
     * - 用于用户登录的唯一标识
     * - 数据库约束：非空、唯一
     * - 长度限制：默认255字符
     */
    @Column(nullable = false, unique = true)
    private String username;

    /**
     * 密码
     * - 存储BCrypt加密后的密码，确保安全性
     * - 数据库约束：非空
     * - 明文密码不会存储，只存储加密后的哈希值
     */
    @Column(nullable = false)
    private String password;

    /**
     * 邮箱地址
     * - 用于找回密码、接收通知等
     * - 数据库约束：非空、唯一
     * - 格式验证：由业务层进行格式校验
     */
    @Column(nullable = false, unique = true)
    private String email;

    /**
     * 手机号码
     * - 用于接收短信验证码、找回密码等
     * - 可选字段，可以为null
     * - 数据库列名：phone_number
     */
    @Column(name = "phone_number")
    private String phoneNumber;

    /**
     * 用户地址
     * - 用户收货地址信息
     * - 可选字段，可以为null
     * - 长度限制：500字符，支持较长地址
     * - 数据库列名：address
     */
    @Column(name = "address", length = 500)
    private String address;

    /**
     * 昵称
     * - 用户显示名称，可用于个人中心展示
     * - 可选字段，可以为null
     * - 数据库列名：nick_name
     */
    @Column(name = "nick_name")
    private String nickName;

    /**
     * 头像URL
     * - 用户头像图片的存储地址
     * - 可选字段，可以为null
     * - 数据库列名：avatar_url
     */
    @Column(name = "avatar_url")
    private String avatarUrl;

    /**
     * 性别
     * - 枚举类型，使用字符串存储
     * - 数据库约束：非空
     * - 默认值：Gender.UNKNOWN（未知）
     */
    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    private Gender gender = Gender.UNKNOWN;

    /**
     * 最后登录时间
     * - 记录用户最后一次成功登录的时间
     * - 用于安全分析、活跃度统计等
     * - 可选字段，可以为null（新注册用户可能从未登录）
     * - 数据库列名：last_login_time
     */
    @Column(name = "last_login_time")
    private LocalDateTime lastLoginTime;

    /**
     * 账户启用状态
     * - true：账户启用，可以正常登录
     * - false：账户禁用，无法登录
     * - 数据库约束：非空
     * - 默认值：true（新用户默认启用）
     */
    @Column(nullable = false)
    private Boolean enabled = true;

    /**
     * 账户锁定状态
     * - true：账户被锁定，无法登录
     * - false：账户未锁定，可以正常登录
     * - 数据库约束：非空
     * - 默认值：false（新用户默认不锁定）
     */
    @Column(nullable = false)
    private Boolean locked = false;

    /**
     * 用户类型
     * - 区分不同类型的用户权限
     * - 枚举类型，使用字符串存储
     * - 默认值：UserType.CUSTOMER（普通用户）
     * - 数据库列名：user_type
     */
    @Enumerated(EnumType.STRING)
    @Column(name = "user_type")
    private UserType userType = UserType.CUSTOMER;

    /**
     * 认证方式
     * - 用户通过何种方式注册/登录
     * - 枚举类型，使用字符串存储
     * - 默认值：AuthProvider.LOCAL（本地认证）
     * - 数据库列名：auth_provider
     */
    @Enumerated(EnumType.STRING)
    @Column(name = "auth_provider")
    private AuthProvider authProvider = AuthProvider.LOCAL;

    /**
     * 第三方认证ID
     * - 当使用第三方认证时，存储第三方平台的用户ID
     * - 可选字段，可以为null
     * - 例如：微信openid、QQ openid等
     * - 数据库列名：provider_id
     */
    @Column(name = "provider_id")
    private String providerId;

    /**
     * 性别枚举
     * - MALE：男性
     * - FEMALE：女性  
     * - UNKNOWN：未知/未设置
     * 
     * 用途：用于用户性别信息的存储和展示
     */
    public enum Gender {
        MALE, FEMALE, UNKNOWN
    }

    /**
     * 用户类型枚举
     * - CUSTOMER：普通用户，具有基本的购物权限
     * - ADMIN：管理员，具有系统管理权限
     * - SUPER_ADMIN：超级管理员，具有所有管理权限
     * - MERCHANT：商家，具有商品管理和订单处理权限
     * 
     * 用途：用于区分不同用户角色的权限级别
     */
    public enum UserType {
        CUSTOMER, ADMIN, SUPER_ADMIN, MERCHANT
    }

    /**
     * 认证方式枚举
     * - LOCAL：本地认证，使用用户名/密码登录
     * - WECHAT：微信认证，使用微信openid登录
     * - QQ：QQ认证，使用QQ openid登录  
     * - WEIBO：微博认证，使用微博openid登录
     * 
     * 用途：记录用户通过何种方式注册和登录系统
     */
    public enum AuthProvider {
        LOCAL, WECHAT, QQ, WEIBO
    }
}